CLI Complete Technical Reference

This reference documents every command-line option, environment variable, exit code, and execution behavior supported by cli.py and the void-builder console script.

Command Syntax

void-builder [ARCHITECTURE] [OPTIONS]
# or:
python3 cli.py [ARCHITECTURE] [OPTIONS]

Positional Arguments

ARCHITECTURE

  • Description: Target architecture or hardware platform profile.

  • Allowed Values:

    • x86_64 (default)

    • x86_64-musl

    • i686

    • aarch64

    • aarch64-musl

    • armv7l

    • armv7l-musl

    • rpi-aarch64

    • rpi-armv7l

    • rpi-armv6l

    • pinebookpro

    • asahi

  • Default: x86_64

Presets & Editions

-P PRESET, --preset PRESET

  • Description: Pre-defined unified profile preset from configs/presets/. Configures desktops, package sets, kernel, bootloader, services, and repositories in a single flag.

  • Available Presets:

    • minimal: Minimal console/server system without X11/Wayland.

    • desktop-xfce: Fast and lightweight XFCE workstation with LightDM.

    • desktop-kde: Modern KDE Plasma 6 environment.

    • desktop-gnome: GNOME 4x desktop with GDM.

    • rescue-sysadmin: Forensics, disk rescue, partition recovery, and network diagnostic tools (GParted, TestDisk, ddrescue, Wireshark, Nmap).

    • developer: Comprehensive developer environment (Rust, Go, Python, Podman, Neovim, Zsh, Clang, CMake, Git).

    • gaming: Steam, Vulkan drivers, MangoHud, GameMode, Wine, and automated multilib/nonfree repository enablement.

Performance & Speed Flags

--fast, --quick

  • Description: Activates ultra-fast build pipeline.

    • Switches compression to zstd with level 3 (5x to 10x faster than XZ).

    • Optimizes SquashFS block size to 256K.

    • Enables fast disk formatting (fast_commit and lazy inode table initialization).

--tmpfs

  • Description: Stages and mounts the entire workdir/ build tree inside RAM (tmpfs), boosting I/O throughput (3x-5x faster) and preventing SSD/NVMe write wear. Automatically unmounts on completion.

--benchmark

  • Description: Records and prints a structured execution timing report measuring each build stage (Toolchain/Chroot setup, Package installation, Post-install customizations, Bootloader generation, SquashFS compression, and Final artifact generation).

-j JOBS, --jobs JOBS

  • Description: Number of CPU threads to allocate for multi-threaded compression and packaging (default: all available CPU cores).

Execution Modes & Actions

--mode {mock,real}

  • Description: Execution mode.

    • mock: Non-root simulation. Validates configurations, simulates XBPS installation, writes placeholder images.

    • real: Performs actual package downloading, mounting, chroot operations, and binary image creation. Requires root / sudo.

  • Default: mock

--dry-run

  • Description: Alias for --mode mock.

--build-calamares

  • Description: Compile the Calamares package from custom_packages/calamares/ and exit.

--with-calamares

  • Description: Recompile Calamares and inject the resulting local repository into the image build.

--build-python-packages

  • Description: Compile all custom Python library packages and exit.

--with-python-packages

  • Description: Compile all custom Python library packages and add the python-libraries profile.

--with-custom-repo

  • Description: Reuse the indexed custom_packages/ repository. This skips Python compilation when matching target-architecture packages are already present and adds the repository to the image build.

-i, --interactive

  • Description: Launches the interactive configuration wizard in the terminal, guiding the user step-by-step through architecture, preset, format, and mode selection.

--check, --validate

  • Description: Runs comprehensive configuration audit (JSON file integrity, profile resolution, package list assembly) and exits without building.

  • Exit Code: 0 on success, 1 on validation failure.

--clean-cache

  • Description: Clears downloaded XBPS packages and cached stage seed tarballs (cache/xbps, cache/tarballs), then exits.

System & Localization Overrides

--hostname HOSTNAME

  • Description: Overrides system hostname (written to /etc/hostname).

--locale LOCALE

  • Description: Overrides system default locale (e.g. pt_PT.UTF-8, en_US.UTF-8, de_DE.UTF-8). Configures /etc/default/libc-locales and /etc/locale.conf.

--timezone TIMEZONE

  • Description: Overrides system timezone (e.g. Europe/Lisbon, America/Sao_Paulo, UTC). Sets /etc/localtime.

--keymap KEYMAP

  • Description: Overrides console keymap (e.g. pt-latin1, br-abnt2, us). Configures /etc/rc.conf.

Security & User Management

--root-password PASSWORD

  • Description: Sets the root user password directly during system configuration.

--lock-root

  • Description: Disables/locks the root account password for security (passwd -l root).

--live-password PASSWORD

  • Description: Sets a custom password for the live user (default: live).

--ssh-key PATH

  • Description: Path to an SSH public key file to inject into /root/.ssh/authorized_keys and /home/<live_user>/.ssh/authorized_keys with secure permissions (0700/0600). Can be specified multiple times.

--ssh-pubkey "KEY"

  • Description: Direct SSH public key string to append to authorized keys.

Lifecycle Hooks Engine

--hook PHASE:PATH

  • Description: Registers a custom shell hook script to be executed at a specific build stage.

  • Phases:

    • pre-install: Runs before XBPS installs packages.

    • post-install: Runs inside the chroot after package installation and configuration.

    • pre-iso: Runs outside the chroot before SquashFS/disk image compression.

    • post-iso: Runs after output artifacts and checksums are finalized.

  • Example: --hook post-install:configs/hooks/post-install.example.sh

Output & Formats

--format {iso,img,raw,qcow2,vdi,vmdk,vhdx,tarball}

  • Description: Target build artifact format.

    • iso: Hybrid ISO 9660 image with BIOS/UEFI bootloaders for live booting, CDs, DVDs, and flash drives.

    • qcow2: QEMU / KVM Copy-On-Write virtual machine disk image (with built-in compression).

    • vdi: VirtualBox Virtual Disk Image.

    • vmdk: VMware Workstation / ESXi Virtual Machine Disk.

    • vhdx / vhd: Microsoft Hyper-V Virtual Hard Disk.

    • img / raw: Partitioned raw disk image (VFAT /boot + EXT4 /) ready for flashing to SD cards, USBs, and eMMC.

    • tarball: Compressed .tar.xz or .tar.zst rootfs archive for containers, Docker, LXC, and stage bootstrapping.

  • Default: iso

--compression {xz,zstd,gzip}

  • Description: Compression algorithm for SquashFS container and Dracut initramfs image. Default: xz (or zstd with --fast).

--compress-image, --compress-output, --compress

  • Description: Compresses final raw disk images (.img / .raw) with multi-threaded compression (.img.xz or .img.zst) for smaller download sizes in distribution.

--save-config PATH

  • Description: Exports the assembled build configuration snapshot as JSON to the specified path for documentation and reproducible builds.

--use-tarball [SOURCE], --tarball [SOURCE]

  • Description: Rapidly builds target ISO/image by unpacking a pre-built base system stage seed (.tar.xz / .tar.zst), running xbps-install -Syu inside the chroot, and layering requested desktop/delta package profiles.

--create-tarball

  • Description: Saves the bootstrapped base rootfs as a reusable stage seed tarball in output/stage_seeds/void-base-<arch>.tar.xz and cache/tarballs/void-base-<arch>.tar.xz.

--generate-manifest / --no-manifest

  • Description: Enables/disables creation of .sha256, .sha512, .md5, and .manifest.json files alongside the output image. Default: enabled.

Exit Codes

  • 0: Successful execution / validation.

  • 1: Build failure, configuration validation error, or permission error.

  • 127: Missing system command dependencies.